Skip to content

Upgrade MCP SDK to v1.25.1 #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
mattzcarey wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Upgrade MCP SDK to v1.25.1 #752

mattzcarey wants to merge 5 commits into from
+1,089 −138

Conversation

@mattzcarey
Copy link
Contributor

@mattzcarey mattzcarey commented Dec 24, 2025

No description provided.

@changeset-bot
Copy link

changeset-bot bot commented Dec 24, 2025 •
edited
Loading

⚠️ No Changeset found

Latest commit: 50cb24b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@claude
Copy link

claude bot commented Dec 24, 2025 •
edited
Loading

Claude Code Review

Summary: MCP SDK upgrade from v1.23.0 to v1.25.1 with SSE resumability and enhanced error handling. Implementation looks solid with comprehensive test coverage.

Issues Found

1. EventStore optional method could cause runtime errors (packages/agents/src/mcp/worker-transport.ts:294)

const eventStreamId = await this.eventStore.getStreamIdForEventId?.(lastEventId);

Using optional chaining on a potentially undefined method is fine, but if eventStore exists but doesn't implement getStreamIdForEventId, this silently returns undefined. Consider validating the EventStore interface implementation or documenting this optional method requirement.

2. Incomplete stream cleanup in closeSSEStream (packages/agents/src/mcp/worker-transport.ts:773-791)
The method iterates through all requestToStreamMapping entries to clean up but doesn't call this.streamMapping.delete(streamId) after the loop. This leaves the streamId in the mapping even though the stream is cleaned up, potentially causing memory leaks.

3. Example CORS configuration uses lowercase header name (examples/mcp-server/src/index.ts:35)

"Access-Control-Allow-Headers": "Content-Type, Accept, mcp-session-id, mcp-protocol-version"

Header names mcp-session-id and mcp-protocol-version are lowercase, but the constant uses MCP-Protocol-Version (uppercase). While HTTP headers are case-insensitive, consistency with the codebase constant MCP_PROTOCOL_VERSION_HEADER would be better.

Minor Observations

  • Removed patch file suggests upstream fix - good to see this dependency cleaned up
  • Test coverage is excellent (640 new lines for worker-transport, 138 for errors)
  • Error handling improvements with getErrorCode helper properly handle the new StreamableHTTPError format
  • Documentation for new features (resumability, session callbacks) is clear

Testing

The PR adds comprehensive tests for:

  • Error code detection (errors.test.ts)
  • SSE resumability and Last-Event-ID handling (worker-transport.test.ts)
  • CORS and protocol version handling

No test gaps identified.

agents-git-bot bot pushed a commit to cloudflare/cloudflare-docs that referenced this pull request Dec 24, 2025
@github-actions @claude
Sync docs for PR #752: Upgrade MCP SDK to v1.25.1
b09c50e 
This sync updates the documentation to reflect the following changes from
cloudflare/agents PR #752:

## API Changes

### WorkerTransportOptions (mcp-handler-api.mdx)
- Added `onsessionclosed` callback that fires when a session is closed via
  DELETE request
- Added `eventStore` option for SSE resumability support, enabling clients to
  reconnect and resume using Last-Event-ID header
- Added `retryInterval` option to control client reconnection timing for
  polling behavior
- Added `closeSSEStream()` method to WorkerTransport class for implementing
  polling behavior during long-running operations
- Updated `sessionIdGenerator` description to clarify it can return undefined
  for stateless mode

### MCPTransportOptions (mcp-client-api.mdx)
- Added `connectionTimeoutMs` option (default: 15000ms) to prevent infinite
  hangs when connecting to MCP servers. Particularly useful when proxies strip
  SSE newline terminators.

### New Example (transport.mdx)
- Added documentation for the new `mcp-server` example showing how to use
  `WebStandardStreamableHTTPServerTransport` from the MCP SDK directly without
  the agents package. This is the simplest way to create stateless MCP servers
  on Cloudflare Workers.

Related PR: cloudflare/agents#752

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@agents-git-bot agents-git-bot bot mentioned this pull request Dec 24, 2025
Open
agents-git-bot bot pushed a commit to cloudflare/cloudflare-docs that referenced this pull request Dec 24, 2025
@github-actions
docs: add stateless MCP server guide and update MCP documentation
4337e31 
This commit documents the new stateless MCP server approach introduced in PR #752 (Upgrade MCP SDK to v1.25.1).

Changes:
- Add new stateless-mcp-server.mdx guide demonstrating WebStandardStreamableHTTPServerTransport usage
- Update MCP index page to explain both stateless and McpAgent-based approaches
- Update remote-mcp-server guide to clarify it uses McpAgent and link to stateless option
- Document the simplest way to create MCP servers on Cloudflare Workers

The new example (examples/mcp-server) uses the MCP SDK directly without the agents package, providing a zero-config stateless option that is simpler for basic use cases.

Related PR: cloudflare/agents#752
@pkg-pr-new
Copy link

pkg-pr-new bot commented Dec 24, 2025 •
edited
Loading

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@752

commit: 50cb24b

agents-git-bot bot pushed a commit to cloudflare/cloudflare-docs that referenced this pull request Dec 24, 2025
@github-actions @claude
docs: Add MCP SDK v1.25.1 documentation
2c52cc6 
Document the MCP SDK upgrade from v1.23.0 to v1.25.1 with the following updates:

- Add new section on using MCP SDK directly without Agents SDK
- Document the new mcp-server example using WebStandardStreamableHTTPServerTransport
- Add documentation for new WorkerTransport options:
  - onsessionclosed callback for session cleanup
  - eventStore for connection resumability support
  - retryInterval for SSE polling behavior control

Related to cloudflare/agents#752

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
agents-git-bot bot pushed a commit to cloudflare/cloudflare-docs that referenced this pull request Dec 29, 2025
@github-actions @claude
docs: add changelog entry for MCP SDK v1.25.1 upgrade
691de25 
- Document new WorkerTransport features: eventStore, onsessionclosed, retryInterval
- Highlight new mcp-server example with stateless guide
- Explain improved error handling and migration notes

Related to cloudflare/agents#752

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mattzcarey @threepointone